EasyGem - 5. The Utility Library

Reference List Window Library -turn page- Reference List Utility Library

Contents | Start

The Utility Library

5. Utility Library

5.1 Utility Library

Reference List Utility Library

5.1 Utility Library

This chapter offers you additional EasyGem commands, which are helpful to you when programming your computer but do not concern menus, dialog boxes, or windows.

Get_Mouse R Mouse_X,R Mouse_Y

Queries mouse position.

This procedure delivers the position for the mouse on the real screen and therefore corresponds to the BASIC functions MOUSEX and MOUSEY. However, the position is always indicated in global coordinates, while the BASIC functions return the mouse position in local coordinates of the currently active Omikron Basic output window. If no Omikron Basic output windows have been set up, then both values are of course identical.

You probably already noticed that in some other programs the mouse cursor changes its shape depending on the task and application being performed (e.g., cross or wristwatch instead of arrow). This can be achieved through the following EasyGem command:

Set_Cursor Cursor_No

Set shape of mouse cursor.

In Cursor_No, you can pass a number between 0 and 4 or 128 and 255, which corresponds to the following shapes:

0 The default arrow cursor.

1 The so-called I-beam cursor. This shape is usually used for word processing.

2 The cross cursor. It consists of a little cross and usually finds application in graphics programs.

3 The plus cursor. As can be deducted from its name, this cursor symbol looks like a plus sign. One should choose this shape if certain areas are to be selected.

4 The watch cursor has the shape of a wristwatch and signals that an operation requiring a bit more time is being executed.

128-255 These numbers correspond to a cursor shape that is located as a resource of the type "crsr" in the resource fork of your program. The value 128 is by default connected to the Berkhan cursor, which you already know from the Omikron Basic program.
Nevertheless, you can also use a resource editor (e.g., ResEdit by Apple) and modify this cursor or define additional cursor shapes with higher numbers.

Easy_Alert Defaultbutton,Boxstring$[,R Button]

Display an alert box.

This procedure corresponds to the BASIC command FORM_ALERT. It is feasible that future versions of EasyGem will offer Easy_Alert with improved characteristics (e.g., movable title bar). Therefore, we would already recommend the present use of Easy_Alert instead of FORM_ALERT.

Easy_Fsel R Fsspec$,R Reply$,Title$,R Sel

Display a fileselect box.

The command Easy_Fsel displays a fileselect box on the screen, just as the BASIC command FILESELECT does. Since we expect to expand this command in future EasyGem versions as well, we recommend to substitute FILESELECT with Easy_Fsel already at this point in time.

The meaning of the individual variables is as follows:

Fsspec$ A file name can be passed in Fsspec$ when StandardPutFile (Sel=1) is used. This file name is then entered into the fileselect box as the default name.
The FileSpecificationRecord of the chosen file will be returned in Fsspec$ after the box has been exited.

Reply$ If StandardGetFile (Sel=0) is used, a file type list may be passed in Reply$ (e.g., "TEXTPICT"). In that case, only the file types indicated in this list are actually displayed.
This variable always contains the FileReplyRecord after Easy_Fsel has been returned. The FileReplyRecord yields additional information such as e.g., file type about the chosen file. See also: Omikron Basic Manual, the chapter discussing the most important data structures of the MacOS.

Title$ Title$ - in conjunction with StandardPutFile (Sel=1) - may be used to define a title above the file name. When using StandardGetFile (Sel=0), this variable has no significance.

Sel This variable may be used on the one hand to determine if you want to load a file (Sel=0) or save a file (Sel=1), on the other hand, it will yield information about whether the fileselect box was exited with 'Cancel.' In that case, Sel=0 and otherwise Sel=1.

Since modern computers have colored displays by default, programmers are faced with the problem on how to offer the user a simple way to select a specific color (e.g., for a text or drawing pen). The following EasyGem command offers the possibility to call up a dialog box, which is then used to choose a variety of colors easily and simply.

Pick_Color X,Y,Prompt$,Color_In,Color_Out,R Button

Display the color picker dialog box.

The meaning of the individual variables is as follows:

X,Y This is used to determine where on the screen the dialog box is supposed to appear. X and Y define the upper left-hand corner of the dialog box. If X=0 and Y=0, the dialog box will be displayed centered.

Prompt$ This parameter may be used to pass a prompt. A prompt is a short text, which is shown in the upper part of the dialog box (e.g., "Please choose a color, ").

Color_In
Color_Out Color indexes (a number between 0 and 255) have to be passed in this parameter. Color_In then contains the index of the input color. The corresponding color hue or tint is shown in the upper right-hand side of the dialog box. The chosen color is registered in Color_Out, if the box has been exited using 'OK', otherwise Color_Out will not change the color.

Button This variable equals zero if Pick_Color has been exited using 'Cancel,' otherwise it is unequal zero.

The color picker dialog box allows the user to choose colors in various different color spaces (e.g., RGB, CYMK, HLS, etc.), which therefore represents a very professional type of color selection. But please remember that depending on the set pixel depths not all desired colors can actually be realized on screen.

Especially in the case of scientific applications, it is often necessary or desired to depict a data set of a two-dimensional field (measuring or computational data) in color, because this facilitates any interpretation of the data significantly. This task is child's play using the following procedure.

Display_Data &Dat(,),Dat_W,Dat_S,&Col(),
Ix,Iy,Iw,Ih,X,Y,W,H

Display data set.

The meaning of the individual parameters is as follows:

Dat(,) This fields contains the measured or computed values, which you would like to use for the visualization. The field has to be an integer field (byte, short or long), since the values are after all going to be interpreted as an index within a color palette and only whole numbers may be used for that purpose.
Byte fields are quite sufficient for most applications. This enables the use of 256 different colors. Some special circumstances, however, might benefit from using short integers (up to 32768 colors) or long integers (practically an unlimited number of colors). If your source data is located in a floating point field, you have to transfer them into an integer field first and renormalize them during the transfer in such a way that only positive numbers occur in an interval, for which the color map has been defined in Col().

Dat_W This is the width of a row, i.e., the value of the first index for which the field Dat(,) has been dimensioned, plus one. For example: DIM Dat(639,399):Dat_W=640

Dat_S This parameter indicates how many bytes are taken by a field element. Here, in the case of byte fields, 1 has to be passed, in the case of short integer fields 2, and 4 when dealing with long integer fields.

Col() This field has to be a long integer field and contains the colors in RGB values. Each field element occupies four bytes. The first byte is free. With 256 colors or less, it is here possible to enter, e.g., an index. The red component is located in the second byte, the green component in the third, and the blue component of the color belonging to the corresponding index in the fourth (each 0 to $FF).

Important: A color has to be defined in Col() for each value in Dat(,). Therefore, Col() has to be at least dimensioned to the largest of the values contained in Dat(,) and has to be filled with meaningful color values.

Ix,Iy,
Iw,Ih These four parameters determine which part of the field passed in Dat(,) is supposed to be depicted. The values are to be understood in terms of field indices. For example: If the the data is contained in a matrix such as Dat(639,399) and you indicate Ix=160 and Iw=320, then these field elements with a first index greater or equal 160 and less than 480 are used for the depiction. Iy and Ih determine the interval for the second index accordingly.

X,Y,
W,H These four parameters define the target area on the active graphics port (set with Gwin_Activate, Win_Activate or GRAF_PORT). If Iw<>W or Ih<>H, then the picture will be shaped in such a ways as to make it fit precisely into the target area.

This is a very powerful procedure, which will facilitate and ease many tasks. However, it is also very easily possible to crash your computer if false parameters are passed. Special attention should be paid to Dat(,) - it should not contain any negative values. Also, make sure that Dat_W and Dat_S are correct and that Col() was dimensioned sufficiently.
Ample BASIC memory has to be allocated for this task with COMPILER "BAS_MEM X" since most of the employed fields have to be rather large to effect a detailed depiction on the screen. An alternate option is to request memory directly from the Mac OS and to deposit your data there the same way one would deposit data in a two-dimensional field. Use the command MAC_OS Handle;1,"NewHandle",Size for this task. This function returns the handle (pointer to a pointer) of the requested memory. This handle can then be passed to the procedure Display_Data instead of &Dat(,). However, do not forget to lock the memory area using MAC_OS ;1,"HLock",Handle before using it. The advantage of this method is that the memory does not have to be from the limited BASIC memory, but rather may originate in the application heap or any other free memory section. The Mac OS functions required for this task are described in further detail in "Inside Macintosh, Memory."
The program EasyFractal.BAS in the DEMO folder shows one of the possible application uses for the procedure Display_Data.

Reference List Window Library -turn page- Reference List Utility Library

Contents | Start

© 1998-1999 Berkhan-Software
www.berkhan.com | Home

5. Utility Library
5.1	Utility Library
Reference List Utility Library

0	The default arrow cursor.
1	The so-called I-beam cursor. This shape is usually used for word processing.
2	The cross cursor. It consists of a little cross and usually finds application in graphics programs.
3	The plus cursor. As can be deducted from its name, this cursor symbol looks like a plus sign. One should choose this shape if certain areas are to be selected.
4	The watch cursor has the shape of a wristwatch and signals that an operation requiring a bit more time is being executed.
128-255	These numbers correspond to a cursor shape that is located as a resource of the type "crsr" in the resource fork of your program. The value 128 is by default connected to the Berkhan cursor, which you already know from the Omikron Basic program. Nevertheless, you can also use a resource editor (e.g., ResEdit by Apple) and modify this cursor or define additional cursor shapes with higher numbers.

The meaning of the individual variables is as follows:
Fsspec$	A file name can be passed in Fsspec$ when StandardPutFile (Sel=1) is used. This file name is then entered into the fileselect box as the default name. The FileSpecificationRecord of the chosen file will be returned in Fsspec$ after the box has been exited.
Reply$	If StandardGetFile (Sel=0) is used, a file type list may be passed in Reply$ (e.g., "TEXTPICT"). In that case, only the file types indicated in this list are actually displayed. This variable always contains the FileReplyRecord after Easy_Fsel has been returned. The FileReplyRecord yields additional information such as e.g., file type about the chosen file. See also: Omikron Basic Manual, the chapter discussing the most important data structures of the MacOS.
Title$	Title$ - in conjunction with StandardPutFile (Sel=1) - may be used to define a title above the file name. When using StandardGetFile (Sel=0), this variable has no significance.
Sel	This variable may be used on the one hand to determine if you want to load a file (Sel=0) or save a file (Sel=1), on the other hand, it will yield information about whether the fileselect box was exited with 'Cancel.' In that case, Sel=0 and otherwise Sel=1.

The meaning of the individual variables is as follows:
X,Y	This is used to determine where on the screen the dialog box is supposed to appear. X and Y define the upper left-hand corner of the dialog box. If X=0 and Y=0, the dialog box will be displayed centered.
Prompt$	This parameter may be used to pass a prompt. A prompt is a short text, which is shown in the upper part of the dialog box (e.g., "Please choose a color, ").
Color_In Color_Out	Color indexes (a number between 0 and 255) have to be passed in this parameter. Color_In then contains the index of the input color. The corresponding color hue or tint is shown in the upper right-hand side of the dialog box. The chosen color is registered in Color_Out, if the box has been exited using 'OK', otherwise Color_Out will not change the color.
Button	This variable equals zero if Pick_Color has been exited using 'Cancel,' otherwise it is unequal zero.

The meaning of the individual parameters is as follows:
Dat(,)	This fields contains the measured or computed values, which you would like to use for the visualization. The field has to be an integer field (byte, short or long), since the values are after all going to be interpreted as an index within a color palette and only whole numbers may be used for that purpose. Byte fields are quite sufficient for most applications. This enables the use of 256 different colors. Some special circumstances, however, might benefit from using short integers (up to 32768 colors) or long integers (practically an unlimited number of colors). If your source data is located in a floating point field, you have to transfer them into an integer field first and renormalize them during the transfer in such a way that only positive numbers occur in an interval, for which the color map has been defined in Col().
Dat_W	This is the width of a row, i.e., the value of the first index for which the field Dat(,) has been dimensioned, plus one. For example: DIM Dat(639,399):Dat_W=640
Dat_S	This parameter indicates how many bytes are taken by a field element. Here, in the case of byte fields, 1 has to be passed, in the case of short integer fields 2, and 4 when dealing with long integer fields.
Col()	This field has to be a long integer field and contains the colors in RGB values. Each field element occupies four bytes. The first byte is free. With 256 colors or less, it is here possible to enter, e.g., an index. The red component is located in the second byte, the green component in the third, and the blue component of the color belonging to the corresponding index in the fourth (each 0 to $FF). Important: A color has to be defined in Col() for each value in Dat(,). Therefore, Col() has to be at least dimensioned to the largest of the values contained in Dat(,) and has to be filled with meaningful color values.
Ix,Iy, Iw,Ih	These four parameters determine which part of the field passed in Dat(,) is supposed to be depicted. The values are to be understood in terms of field indices. For example: If the the data is contained in a matrix such as Dat(639,399) and you indicate Ix=160 and Iw=320, then these field elements with a first index greater or equal 160 and less than 480 are used for the depiction. Iy and Ih determine the interval for the second index accordingly.
X,Y, W,H	These four parameters define the target area on the active graphics port (set with Gwin_Activate, Win_Activate or GRAF_PORT). If Iw<>W or Ih<>H, then the picture will be shaped in such a ways as to make it fit precisely into the target area.